home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr42 / p16_13a.zip / PLAY16.DOC < prev   
Text File  |  1995-02-25  |  15KB  |  370 lines
  1.  
  2. -- Play16 version 1.3a (24.02.95) - a versatile soundplayer for the Amiga --
  3.  
  4.  
  5. Features in brief
  6. -----------------
  7.  - autodetects and plays several soundfiles, up to 16 bit / 56 kHz / stereo
  8.  - always correct playback speed, even for sounds >28 kHz
  9.  - realtime playback from harddisk, optimized assembler routines
  10.  - optional 14 bit output (less noise but not as good as true 16 bit)
  11.  - automatic or manual audio filter control
  12.  - plays mono sounds on *both* channels, not only on the left one
  13.  - plays (and loops) files that are larger than memory
  14.  - preloading for exactly timed start of playback
  15.  - fast uLaw decompression
  16.  - system friendly audio channel allocation
  17.  - supported Filetypes are:
  18.  
  19.    * Microsoft RIFF-WAVE  (.WAV)  mono / stereo, 8 / 16 bit, linear / uLaw
  20.    * Sun/NeXT Audio       (.AU)   mono / stereo, 8 / 16 bit, linear / uLaw
  21.    * MacroSystem MAUD     (.MAUD) mono / stereo, 8 / 16 bit, linear
  22.    * Apple/SGI/Amiga AIFF (.AIFF) mono / stereo, 8 / 16 bit, linear
  23.    * Amiga IFF-8SVX       (.IFF)  mono / stereo, 8      bit, linear
  24.    * Any raw sound data as long as it matches one of the following:
  25.      -  8 bit signed
  26.      -  8 bit unsigned
  27.      - 16 bit signed, Intel format    (LSB first)
  28.      - 16 bit signed, Motorola format (MSB first)
  29.  
  30.  
  31. What do I need to use Play16?
  32. -----------------------------
  33. Any Amiga running Kickstart/Workbench 2.04 or greater.
  34.  
  35.  
  36. Where do I find the latest version?
  37. -----------------------------------
  38.  - FIDONET: Amiga Venture BBS, Germany (2:243/6050)
  39.  - AmiNET:  mus/play
  40.  
  41.  
  42. What does it do?
  43. ----------------
  44. Basically, Play16 is capable of playing uncompressed and _some_ compressed
  45. soundfiles through Amiga's standard audio device. If the actual resolution
  46. or playback rate exceeds that of the Amiga hardware, realtime conversion
  47. is done so that the sound is being played back correctly.
  48.  
  49. You can even play 16 bit / 44.1 kHz sounds, providing all parts of
  50. your system can keep up with the high data transfer rate and lots
  51. of calculations needed for this task. (In this case an accelerated
  52. Amiga is recommended :-)
  53.  
  54. The two audio channels at each side can be linked to perform as a single
  55. 14 bit channel. Again, this swallows lots of computing power.
  56.  
  57. Anyway, my Amiga 3000-16MHz is fast enough to play an uncompressed soundfile
  58. with full 44.1kHz/14bit output (productivity) directly from harddisk !!!
  59.  
  60. I don't want Play16 to be a program that plays each and every exotic format
  61. that exists somewhere. However, I intend to support as many popular file
  62. types as possible.
  63.  
  64.  
  65. How do I use it?
  66. ----------------
  67. Simply type "Play16 <filename>" and that's it!
  68. All possible options will be explained later. If you set none of them, the
  69. defaults will be used.
  70.  
  71.  
  72. Why Play16?
  73. -----------
  74. 16 bit soundcards are becoming more and more popular, especially on the
  75. PC. The common file format over there is Microsoft's (yuck! :)) RIFF-
  76. WAVE format.
  77. I didn't find any CLI based program to play back 16 bit recordings, on a
  78. standard Amiga, so I decided to write one myself.
  79.  
  80.  
  81. Why CLI based and no GUI?
  82. -------------------------
  83. There are so many GUI based directory utilities, simply use Play16 as an
  84. external player. Consult the manual of your software package on how to
  85. do it. Application example: Assign "Play16 <filename> PRELOAD" to a button
  86. called "Jingle". Select the desired soundfile and press the Jingle-button.
  87. Wait for the appropriate moment and hit the return key - here comes the
  88. sound! Nice when audio dubbing your home videos or even on parties :-)
  89.  
  90.  
  91. How does it work? (technical info)
  92. ----------------------------------
  93. The standard Amiga audio device is limited to 8 bit / 28 kHz playbck
  94. when using DMA. With the introduction of ECS the 28 kHz DMA barrier
  95. was broken - but only if the current displaymode was one with double
  96. scan rate like productivity. The reason for this is the dependency
  97. between video and audio DMA. If you don't have ECS or if you simply
  98. don't want to switch to Productivity just to listen to your desired
  99. sound, Play16 can halve the sample rate during playback.
  100.  
  101. Another way to archieve high output rates is using IRQ. This works no
  102. matter what the displaymode is. I've been experimenting on that long
  103. before I started writing Play16 but there was so much jitter that my
  104. current downsampling method sounds much better.
  105.  
  106. To play back even long sounds, the popular method of double buffering
  107. is used. Alternatively, all data can be loaded into memory before
  108. playback. This is useful when playing short sounds or when loading
  109. the sound from floppy disk or slow CD ROM.
  110.  
  111. The 14 bit output is archieved by setting the first channel on each
  112. side to volume 64 and the second to volume 1. The louder channel then
  113. plays the upper 8 bits as usual while the other channel plays the
  114. 6 most significant bits of the low byte synchronously. Because timing
  115. is very crucial in this case it is nessecary to write directly to
  116. hardware registers instead of using the audio.device. This method may
  117. not work on future amiga models if there ever will be any... :-/
  118.  
  119.  
  120.  
  121. What options are provided?
  122. --------------------------
  123. If you are not familiar with the AmigaOS 2.x commandline template, see
  124. the examples below and consult the AmigaOS manual for furhter information.
  125.  
  126. FAST/S      Do not automatically switch to half sample rate if the
  127.             soundfile's rate exceeds 28 kHz. Use this option when
  128.             running your Amiga in Productivity or similar display
  129.             modes.
  130.  
  131. HIFI/S      Turn on the 14 bit output. Watch out! This is a nasty routine
  132.             that writes directly to some hardware registers. I've done
  133.             everything I can to prevent Play16 from interfering with
  134.             other running tasks in this case but you'll never know...
  135.             Use it with care!
  136.  
  137. FILTER/K    FILTER=ON  : Enable audio filter for playback
  138.             FILTER=OFF : Disable audio filter for playback
  139.             FILTER=AUTO: Turn filter on or off depending on sample rate
  140.             If you don't specify this keyword Play16 will leave the
  141.             hardware registers of the audiofilter completely untouched.
  142.  
  143. SINGLE/S    Use only one buffer rather then two and load all data into
  144.             memory befor playback.
  145.  
  146. BUFFER/N    Buffersize in samples. May vary from 32768 to 131072. The
  147.             amount of allocated memory also depends on whether the sound
  148.             is mono or stereo, 8 bit or 16 bit.
  149.             Default is 65536 samples, values are rounded to multiples of
  150.             32768.
  151.             Note that it is useless to modify this value when in single
  152.             buffer mode :)
  153.  
  154. VERBOSITY/N Sets the level of verbosity.
  155.             0: Just display the banner and error messages
  156.             1: Print additional information about the sound file,
  157.                allocated memory, etc.
  158.             2: Progress information
  159.             3: Debugging information (may look a bit weird :)
  160.             Default is level 0.
  161.  
  162. LOOPS/N     Determines the number of loops to be played.
  163.             Default is 1 loop. (Play the sound once.)
  164.             This option is not yet supported in SINGLE mode.
  165.  
  166. PRELOAD/S   Load enough data into memory for immediate start of playback
  167.             at a keypress
  168.  
  169. RAW/S       Disable autodetect and tell Play16 what the actual format of
  170.             the sound data is.
  171.             However, if Play16 can't detect the filetype it will switch
  172.             to RAW mode automatically. If you don't want this to happen
  173.             you can specify...
  174.  
  175. STRICT/S    Play only files that are supported by the autodetect routine
  176.             Use this if you don't want to be scared by the sudden noisy
  177.             output when trying to play back other data than sound :-)
  178.  
  179. The following options tell Play16 what parameters to use when in RAW mode.
  180. This happens either if you set the RAW keyword or if Play16 could not
  181. identify the file and STRICT was _not_ set.
  182.  
  183. FREQ/N      Sampling frequency in Hz
  184. TRACKS/N    Number of tracks, 1 for mono, 2 for stereo
  185. BITS/N      Resolution in bits, may be 8 or 16
  186. HEADER/N    Length of header: This is the number of bytes to be skipped
  187.                               at the beginning of the file.
  188. UNSIGNED/S  Data is unsigned, not signed (only valid for  8 bit sounds)
  189. INTEL/S     Data is in Intel format      (only valid for 16 bit sounds)
  190. ULAW/S      Data is compressed using the uLaw compression scheme
  191.  
  192. The default settings are: 22050 Hz, mono, 8 bits, no header.
  193.  
  194. Examples:
  195.  
  196. a) Play16 music.wav
  197.     Simply play the file called music.wav once and directly from harddisk.
  198.  
  199. b) Play16 music.wav SINGLE
  200.     Same as above but load all data into memory before playback. Use this
  201.     when loading soundfiles from floppy disk.
  202.  
  203. c) Play16 music.wav SINGLE VERBOSITY=1
  204.     Same as b, but with additional information being printed out.
  205.  
  206. d) Play16 rhythm.wav LOOPS=10
  207.         Play the rhythm as a continuous loop, i.e. over and over again (10 times)
  208.  
  209. e) Play16 explosion.wav SINGLE PRELOAD
  210.     Load the complete explosion sound into memory, then wait for you to hit
  211.     <return> before playback.
  212.  
  213.  
  214. How do I use this RAW mode?
  215. ---------------------------
  216. Umm, err, difficult to explain, even harder to understand...
  217. Well, if you know the data format of the soundfile, simply set RAW, FREQ,
  218. TRACKS, BITS, UNSIGNED and INTEL accordingly. If you don't, the only
  219. way to find it out is by trial and error :) Here are some tips to make
  220. it a bit easier:
  221.  
  222. Don't set HEADER to an odd number. (Leave it at 0, first.)
  223. If you set BITS to 16 and hear nothing but noise, try to set INTEL.
  224. If you set BITS to 8 and the sound is distorted, try to set UNSIGNED.
  225. If the above does not help, try different combinations of BITS, INTEL
  226. and UNSIGNED.
  227.  
  228. If you manage to get a recognisable sound output which is either too
  229. fast or too slow, start experimenting on TRACKS and FREQ.
  230.  
  231. If you want to play known files and raw ones without changing the command
  232. line, simply specify all you know about the raw data and leave out the
  233. RAW and the STRICT keyword. If Play16 can indentify the file it will use
  234. its parameters. If the filetype is unknown your specified parameters will
  235. be used instead.
  236.  
  237.  
  238. Legal stuff
  239. -----------
  240. Play16 is copyrighted freeware. It may be distributed freely as long as
  241. no modifications are made to the executable and this document. A nominal
  242. fee may be asked to cover distribution costs.
  243.  
  244. Play16 may not be used for any commercial purposes or included with any
  245. commercial product without the written permission of the author.
  246.  
  247. No responsibilities are taken for damaged speakers, amplifiers, Amigas
  248. or any other components or data involved while using Play16.
  249.  
  250. Although I've done some beta testing I can't guarantee that Play16 will
  251. not crash! If you find any bugs, let me know.
  252.  
  253.  
  254. Miscellaneous
  255. -------------
  256. I don't claim Play16 to be fast. I've done some optimizing - but because
  257. the loader/converter module is a universial one, more data is actually
  258. being moved around different memory blocks than needed for playback.
  259. I've implemented separate optimized routines for 8 bit and 14/16 bit.
  260. This method will provide the basis for future enhancements in the playback
  261. routine like soundcard support.
  262.  
  263. * Please note that English is not my native language :)
  264.  
  265. I can be reached at...
  266.  
  267. Internet: wenzel@unixserv.rz.fh-hannover.de (preferred)
  268.           Thomas_Wenzel@aventure.fido.de
  269. Fido:     2:243/6050.28 or 2:241/1035.6
  270.           Mail routing _is_sometimes_ unreliable in FidoNet :-(
  271.  
  272. If you use this program, please send me a mail. I'd like to know how many
  273. people are interested in it at all.
  274.  
  275.  
  276. History
  277. -------
  278. V0.5▀   - Initial beta test release
  279.  
  280. V0.6▀   - Optimized the code a bit.
  281.  
  282. V0.7▀   - Fixed some severe bugs that caused Play16 to crash when trying
  283.           to load corrupted files.
  284.  
  285. V0.8▀   - Play16 can now be stopped by pressing ctrl-c during playback. The
  286.           buffer that is currently being played will be finished first.
  287.         - Automatic filter control depending on sample rate.
  288.  
  289. V0.9▀   - Added 'loop'-option. Sample can be played several times.
  290.         - All time consuming routines now in hand optimized assembler code.
  291.  
  292. V1.0▀   - Play16 now uses standard OS2.x commandline template.
  293.           Thanks to Kai for persuading me to do this :)
  294.  
  295. V1.0    - Done some minor bugfixes.
  296.  
  297. V1.1    - Oops! Play16 caused some Enforcer hits. Fixed that.
  298.           Thanks to Rod Schnell for reporting it.
  299.         - Added 'single'-option. Sound can be loaded completely into memory
  300.           before playing. No looping possible in this case yet!
  301.         - Playback time in minutes:seconds displayed if verbose >= 1
  302.         - uLaw decompression for WAVE-Files, using a decoding table
  303.           for maximum speed (didn't do much testing on it, hope it works!)
  304.         - MAUD filetype support (why do there have to be so many formats?)
  305.         - AIFF filetype support
  306.         - ctrl-c now stops playback immediately.
  307.           Thanks to Marc for some programming tips about that.
  308.  
  309. V1.2    - IFF-8SVX filetype support (only uncompressed files!)
  310.         - RAW data support: _Any_ data can be played
  311.         - Preload feature added
  312.         - Fixed a bug that caused illegal memory access (hopefully)
  313.           Thanks to Ignatios Souvatzis for reporting it.
  314.         - Improved chunk handling
  315.  
  316. V1.3    - 14 bit output (finally!)
  317.         - Any file Play16 can't recognise is considered raw data unless
  318.           you set the STRICT keyword
  319.         - Fixed a bug in WAV filetype length determination
  320.         - Advanced audiofilter control / original state will be restored
  321.           after playback
  322.         - More information about sound (AUTHOR or ANNO-Chunk) is being
  323.           printed out if VERBOSE>=1. However, Play16 will *not* search
  324.           the whole file for that string. If it doesn't come before the
  325.           sound data -- bad luck :-)
  326.  
  327. V1.3a   - Bugfix in chunk handling routine: Chunks with an odd length
  328.           were treated incorrectly. This bug accompanied all versions
  329.           of Play16, even V1.0. However, I decided to release a fix now
  330.           instead of letting you wait until V1.4 is finished.
  331.  
  332.  
  333.  
  334. Future plans
  335. ------------
  336. - Wildcard support (!)
  337. - Filerequester if no filename is given
  338. - Workbench icon with tooltype entries
  339. - Settings can be stored in environment variables
  340.   (especially useful for filter setting)
  341. - Stop playing by ctrl-c _or_ lmb (probably by clicking on a gadget)
  342. - other uLaw-formats and almost certainly Creative-VOC support
  343. - Samplitude HDPs and RAPs
  344. - Letting Play16 open a productivity screen for fast DMA
  345. - ADPCM decompression (still having difficulties coding the algorhytm)
  346. - some of the file types saved by Macintosh software (e.g. Sound-Designer)
  347. - Soundcard support
  348.  
  349. Known bugs
  350. ----------
  351. Some files have additional information stored AFTER the waveform data.
  352. Play16 does not recognise that and tries to play the data, resulting
  353. in a short 'blip' at the end of the sound. So far I've only encountered
  354. *some* WAVs that have this additional chunk at the end of the file.
  355.  
  356. Credits
  357. -------
  358. Thanks go to the following persons:
  359.  
  360. Kai Stuke   for many vital hints on C programming and the Amiga
  361.             audio device.
  362.             for beta testing this program.
  363.  
  364. Marc Fⁿhrer for doing some beta testing as well.
  365.             for some hints on optimizing the code.
  366.  
  367. Clete Baker for supplying the AIFF- and SDII specs.
  368.  
  369. And to all the people who wrote me!
  370.